Next: , Up: Agent Categories

6.9.2.1 Category Syntax

A category consists of a name, the list of groups belonging to the category, and a number of optional parameters that override the customizable variables. The complete list of agent parameters are listed below.

agent-groups
The list of groups that are in this category.
agent-predicate
A predicate which (generally) gives a rough outline of which articles are eligible for downloading; and
agent-score
a score rule which (generally) gives you a finer granularity when deciding what articles to download. (Note that this download score is not necessarily related to normal scores.)
agent-enable-expiration
a boolean indicating whether the agent should expire old articles in this group. Most groups should be expired to conserve disk space. In fact, its probably safe to say that the gnus.* hierarchy contains the only groups that should not be expired.
agent-days-until-old
an integer indicating the number of days that the agent should wait before deciding that a read article is safe to expire.
agent-low-score
an integer that overrides the value of gnus-agent-low-score.
agent-high-score
an integer that overrides the value of gnus-agent-high-score.
agent-short-article
an integer that overrides the value of gnus-agent-short-article.
agent-long-article
an integer that overrides the value of gnus-agent-long-article.
agent-enable-undownloaded-faces
a symbol indicating whether the summary buffer should display undownloaded articles using the gnus-summary-*-undownloaded-face faces. Any symbol other than nil will enable the use of undownloaded faces.

The name of a category can not be changed once the category has been created.

Each category maintains a list of groups that are exclusive members of that category. The exclusivity rule is automatically enforced, add a group to a new category and it is automatically removed from its old category.

A predicate in its simplest form can be a single predicate such as true or false. These two will download every available article or nothing respectively. In the case of these two special predicates an additional score rule is superfluous.

Predicates of high or low download articles in respect of their scores in relationship to gnus-agent-high-score and gnus-agent-low-score as described below.

To gain even finer control of what is to be regarded eligible for download a predicate can consist of a number of predicates with logical operators sprinkled in between.

Perhaps some examples are in order.

Here's a simple predicate. (It's the default predicate, in fact, used for all groups that don't belong to any other category.)

     short

Quite simple, eh? This predicate is true if and only if the article is short (for some value of “short”).

Here's a more complex predicate:

     (or high
         (and
          (not low)
          (not long)))

This means that an article should be downloaded if it has a high score, or if the score is not low and the article is not long. You get the drift.

The available logical operators are or, and and not. (If you prefer, you can use the more “C”-ish operators ‘|’, & and ! instead.)

The following predicates are pre-defined, but if none of these fit what you want to do, you can write your own.

When evaluating each of these predicates, the named constant will be bound to the value determined by calling gnus-agent-find-parameter on the appropriate parameter. For example, gnus-agent-short-article will be bound to (gnus-agent-find-parameter group 'agent-short-article). This means that you can specify a predicate in your category then tune that predicate to individual groups.

short
True if the article is shorter than gnus-agent-short-article lines; default 100.
long
True if the article is longer than gnus-agent-long-article lines; default 200.
low
True if the article has a download score less than gnus-agent-low-score; default 0.
high
True if the article has a download score greater than gnus-agent-high-score; default 0.
spam
True if the Gnus Agent guesses that the article is spam. The heuristics may change over time, but at present it just computes a checksum and sees whether articles match.
true
Always true.
false
Always false.

If you want to create your own predicate function, here's what you have to know: The functions are called with no parameters, but the gnus-headers and gnus-score dynamic variables are bound to useful values.

For example, you could decide that you don't want to download articles that were posted more than a certain number of days ago (e.g. posted more than gnus-agent-expire-days ago) you might write a function something along the lines of the following:

     (defun my-article-old-p ()
       "Say whether an article is old."
       (< (time-to-days (date-to-time (mail-header-date gnus-headers)))
          (- (time-to-days (current-time)) gnus-agent-expire-days)))

with the predicate then defined as:

     (not my-article-old-p)

or you could append your predicate to the predefined gnus-category-predicate-alist in your ~/.gnus.el or wherever.

     (require 'gnus-agent)
     (setq  gnus-category-predicate-alist
       (append gnus-category-predicate-alist
              '((old . my-article-old-p))))

and simply specify your predicate as:

     (not old)

If/when using something like the above, be aware that there are many misconfigured systems/mailers out there and so an article's date is not always a reliable indication of when it was posted. Hell, some people just don't give a damn.

The above predicates apply to all the groups which belong to the category. However, if you wish to have a specific predicate for an individual group within a category, or you're just too lazy to set up a new category, you can enter a group's individual predicate in its group parameters like so:

     (agent-predicate . short)

This is the group/topic parameter equivalent of the agent category default. Note that when specifying a single word predicate like this, the agent-predicate specification must be in dotted pair notation.

The equivalent of the longer example from above would be:

     (agent-predicate or high (and (not low) (not long)))

The outer parenthesis required in the category specification are not entered here as, not being in dotted pair notation, the value of the predicate is assumed to be a list.

Now, the syntax of the download score is the same as the syntax of normal score files, except that all elements that require actually seeing the article itself are verboten. This means that only the following headers can be scored on: Subject, From, Date, Message-ID, References, Chars, Lines, and Xref.

As with predicates, the specification of the download score rule to use in respect of a group can be in either the category definition if it's to be applicable to all groups in therein, or a group's parameters if it's to be specific to that group.

In both of these places the download score rule can take one of three forms:

  1. Score rule

    This has the same syntax as a normal Gnus score file except only a subset of scoring keywords are available as mentioned above.

    example:

  2. Agent score file

    These score files must only contain the permitted scoring keywords stated above.

    example:

  3. Use normal score files

    If you don't want to maintain two sets of scoring rules for a group, and your desired downloading criteria for a group are the same as your reading criteria then you can tell the agent to refer to your normal score files when deciding what to download.

    These directives in either the category definition or a group's parameters will cause the agent to read in all the applicable score files for a group, filtering out those sections that do not relate to one of the permitted subset of scoring keywords.